---
title: 导入 & 导出
icon: '#pro/FolderSync'
---

<MetaData
  lang="zh-CN"
  isPro
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-advanced',
      locale: '@univerjs/preset-sheets-advanced/locales/zh-CN',
      style: '@univerjs/preset-sheets-advanced/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs-pro/exchange-client',
      facade: '@univerjs-pro/exchange-client/facade',
      locale: '@univerjs-pro/exchange-client/locale/zh-CN',
      style: '@univerjs-pro/exchange-client/lib/index.css',
    }, {
      client: '@univerjs-pro/sheets-exchange-client',
    }],
    server: '是',
  }}
/>

<Callout type="warning" title="注意事项">
  导入导出功能需要 Univer 服务端支持，请确保你已经正确安装并配置了 Univer 服务端。具体请参考：[升级到 Pro](/guides/sheets/getting-started/pro)
</Callout>

导入和导出功能允许用户通过 Univer 服务端将 `.xlsx` 文件导入到 Univer 文档中，或将文档内容导出为 `.xlsx` 文件，便于与其他办公软件或平台进行交互。

<Callout title="为什么 Univer 通过后端服务实现导入导出？">
  仅通过前端实现的导入导出无论是从性能还是效果上来说都无法满足企业需求，因此我们提供了后端服务来实现导入导出功能。你可以通过一些开源的 XLSX 解析库将文件解析为符合 [`IWorksheetData`](https://reference.univer.ai/zh-CN/interfaces/IWorkbookData) 接口的数据结构，然后通过 Facade API 将数据导入到 Univer 中。
</Callout>

通过菜单栏的导入入口成功导入后，页面左下角会弹出提示框，显示导入成功的信息，并提供访问导入文档的链接。若默认的导入导出行为无法满足你的需求，请查看[《自定义导入文档》](/guides/recipes/tutorials/custom-import)以了解如何自定义导入行为。

## 预设模式

### 安装

<Callout>
  @univerjs/preset-sheets-advanced 的 `UniverSheetsAdvancedPreset` 预设在运行时依赖 `UniverSheetsDrawingPreset` 预设，请先安装 @univerjs/preset-sheets-drawing。
</Callout>

```package-install
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### 使用

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      UniverPresetSheetsCoreZhCN,
      UniverPresetSheetsDrawingZhCN, // [!code ++]
      UniverPresetSheetsAdvancedZhCN, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset({ // [!code ++]
      universerEndpoint: 'http://localhost:3010', // [!code ++]
    }), // [!code ++]
  ],
})
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在预设模式中使用)进行配置。

### 预设与配置

`UniverSheetsAdvancedPreset` 配置项：

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  // Univer Server 的端口地址
  universerEndpoint?: string
  exchangeClientOptions?: {
    // 导入后工作表的最小行数
    minSheetRowCount?: number
    // 导入后工作表的最小列数
    minSheetColumnCount?: number
    /**
     * 导出是否启用服务器端公式计算。启用后，每次导出都会触发服务端公式计算。解决如下问题：
     * 1. WPS 等办公软件打开文件时公式无默认值
     * 2. EXCEL 不启用编辑，无法看到公式计算结果
     * 3. 数组公式存在前缀@，导致无法展开计算结果
     * 注意，此配置需要在协同编辑环境下使用，服务端配置文件需要配置 SSC_SERVER_ENABLED=true。
     */
    enableServerSideComputing?: boolean
    /**
     * 是否在导出时禁用将单元格图片转换为链接。
     * 如果单元格图片源是一个 URL，默认行为是在导出时将该 URL 转换为单元格的值。
     * 由于服务器会下载所有的资源文件，当图片较多时，会消耗大量资源并且耗时较长。
     * @default true
     */
    disableCellImageConversion?: boolean
  }
}
```

## 插件模式

### 安装

```package-install
npm install @univerjs-pro/exchange-client @univerjs-pro/sheets-exchange-client
```

### 使用

```typescript
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client' // [!code ++]
import ExchangeClientZhCN from '@univerjs-pro/exchange-client/locale/zh-CN' // [!code ++]
import { UniverSheetsExchangeClientPlugin } from '@univerjs-pro/sheets-exchange-client' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/exchange-client/facade' // [!code ++]

import '@univerjs-pro/exchange-client/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: mergeLocales(
      ExchangeClientZhCN, // [!code ++]
    ),
  },
})

const UNIVER_SERVER_ENDPOINT = `http://localhost:8000` // [!code ++]

univer.registerPlugin(UniverExchangeClientPlugin, { // [!code ++]
  uploadFileServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/stream/file/upload`, // [!code ++]
  importServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/import`, // [!code ++]
  exportServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/{type}/export`, // [!code ++]
  getTaskServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/exchange/task/{taskID}`, // [!code ++]
  signUrlServerUrl: `${UNIVER_SERVER_ENDPOINT}/universer-api/file/{fileID}/sign-url`, // [!code ++]
  downloadEndpointUrl: `${UNIVER_SERVER_ENDPOINT}/`, // [!code ++]
}) // [!code ++]
univer.registerPlugin(UniverSheetsExchangeClientPlugin) // [!code ++]
```

如果你拥有 Univer 的商业许可证，请参考[在客户端使用许可证](/guides/pro/license#在插件模式中使用)进行配置。

### 插件与配置

`UniverExchangeClientPlugin` 配置项：

```typescript
interface IUniverExchangeClientConfig {
  // Univer Server 的配置
  downloadEndpointUrl?: string
  uploadFileServerUrl?: string
  importServerUrl?: string
  exportServerUrl?: string
  getTaskServerUrl?: string
  signUrlServerUrl?: string
  // 最大超时时间，单位为毫秒
  maxTimeoutTime?: number
  options?: {
    // 导入后工作表的最小行数
    minSheetRowCount?: number
    // 导入后工作表的最小列数
    minSheetColumnCount?: number
    /**
     * 导出是否启用服务器端公式计算。启用后，每次导出都会触发服务端公式计算。解决如下问题：
     * 1. WPS 等办公软件打开文件时公式无默认值
     * 2. EXCEL 不启用编辑，无法看到公式计算结果
     * 3. 数组公式存在前缀@，导致无法展开计算结果
     * 注意，此配置需要在协同编辑环境下使用，服务端配置文件需要配置 SSC_SERVER_ENABLED=true。
     */
    enableServerSideComputing?: boolean
    /**
     * 是否在导出时禁用将单元格图片转换为链接。
     * 如果单元格图片源是一个 URL，默认行为是在导出时将该 URL 转换为单元格的值。
     * 由于服务器会下载所有的资源文件，当图片较多时，会消耗大量资源并且耗时较长。
     * @default true
     */
    disableCellImageConversion?: boolean
  }
}
```

## Facade API

### 导入

#### 导入 `.xlsx` 文件并获取 `unitId`

<Callout type="warning" title="注意事项">
  此方法仅适用于启用了协同编辑的文档导入。
</Callout>

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.importXLSXToUnitIdAsync` 传入 `file` 参数会返回 `unitId`，可以通过 `unitId` 来访问文档。 `file` 参数可以是一个 `File` 对象，也可以是远程文件的 URL。

```typescript
// 接受 File 对象
const unitId = await univerAPI.importXLSXToUnitIdAsync(file)
// 或者接受远程文件的 URL
// const unitId = await univerAPI.importXLSXToUnitIdAsync('https://example.com/filename.xlsx');

// 配合协同编辑自动加载数据一同使用 https://docs.univer.ai/zh-CN/guides/sheets/features/collaboration#loading-collaborative-documents
const url = new URL(window.location.href)
url.searchParams.set('unit', unitId)
url.searchParams.set('type', '2') // 2 的意思是 String(UniverInstanceType.UNIVER_SHEET)

window.location.href = url.toString()

// 或者调用API: univerAPI.loadServerUnit(unitId, 2) 加载文档，具体参数参考 https://reference.univer.ai/zh-CN/classes/FUniver#loadserverunit
```

#### 导入 `.xlsx` 文件并获取 `IWorkbookData`

使用 `univerAPI.importXLSXToSnapshotAsync` 导入 `.xlsx` 文件，会返回 `IWorkbookData` 格式的文档数据。

```typescript
// 接受 File 对象
const snapshot = await univerAPI.importXLSXToSnapshotAsync(file)
// 或者接受远程文件的 URL
// const snapshot = await univerAPI.importXLSXToSnapshotAsync('https://example.com/filename.xlsx');

// 通过快照创建一个新的工作簿
univerAPI.createWorkbook(snapshot)
```

### 导出

#### 通过 `unitId` 导出 `.xlsx` 文件

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.exportXLSXByUnitIdAsync` 传入 `unitId` 参数会返回 `File` 对象。

```typescript
import { downloadFile } from '@univerjs-pro/exchange-client'

const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const file = await univerAPI.exportXLSXByUnitIdAsync(unitId)

// 下载文件
downloadFile(file, 'univer', 'xlsx')
```

#### 通过 `IWorkbookData` 导出 `.xlsx` 文件

使用 `univerAPI.exportXLSXBySnapshotAsync` 传入 `IWorkbookData` 会返回 `File` 对象。

```typescript
import { downloadFile } from '@univerjs-pro/exchange-client'

const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.getSnapshot()
const file = await univerAPI.exportXLSXBySnapshotAsync(snapshot)

// 下载文件
downloadFile(file, 'univer', 'xlsx')
```

## 在 Node.js 服务端进行数据转换

Univer 服务端提供了导入导出的 API，但是服务端转化的数据和 Univer 格式不一致。插件 `@univerjs-pro/exchange-client` 内置了数据转换的工具函数，可以在 Node.js 服务端使用。

### Snapshot 转化为 `IWorkbookData`

导入后得到的 Snapshot JSON 数据需要转化为 `IWorkbookData` 格式的数据才能在 Univer 中使用。

```typescript
import { transformSnapshotJsonToWorkbookData } from '@univerjs-pro/exchange-client'

// json 数据包含 snapshot 和 sheetBlocks
const workbookData = transformSnapshotJsonToWorkbookData(json)
```

### `IWorkbookData` 转化为 Snapshot

导出前需要将 `IWorkbookData` 格式的数据转化为 Snapshot JSON 数据，才能传给服务端进行导出。

```typescript
import { transformWorkbookDataToSnapshotJson } from '@univerjs-pro/exchange-client'

const snapshotJson = transformWorkbookDataToSnapshotJson(workbookData)
```
